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REMARKS 

I. Summary of Amendments 

By this amendment, Applicants propose amending claims 55, 66, 67, and 69-73. 
Claims 55-74 are pending. 

II. Summary of Office Action 

In the last Office Action, the Examiner 

(a) rejected claims 66-73 under 35 U.S.C. § 1 1 2, 

(b) rejected claims 55-64 under 35 U.S.C. § 1 01 , 

(c) rejected claims 55-58, 64-68, and 74 under 35 U.S.C. § 1 02(e) over 
"Java Virtual Machine Profiler Interface (JVMPI)," November 1 1 , 1998, 
and 

(d) rejected claims 59-63 and 69-73 under 35 U.S.C. § 1 03(a) over JVMPI 
and U.S. Patent No. 5,857,210 (Tremblay). 

III. Rejection under 35 U.S.C. § 112 

Applicants propose amending claims 66, 67, and 69-73, as shown above in the 
listing of claims, to correct a typographical error. In view of those proposed 
amendments, Applicants request withdrawal of the rejection of claims 66, 67, and 69-73 
under 35 U.S.C. § 112. 

IV. Rejection under 35 U.S.C. § 101 

Applicants traverse the rejection of claims 55-64 under 35 U.S.C. § 101 . The 
Examiner on page 3 of the Office Action alleges that claim 55 does not appear to 
contain elements related to a device or physical apparatus. Applicants respectfully 
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disagree. In order to advance the prosecution of this application, however, Applicants 

have proposed amending independent claim 55 to recite "a processor" and "memory," 

as shown above in the listing of claims. Accordingly, the rejection of claim 55 and its 

dependent claims 56-64 under 35 U.S.C. § 101 should be withdrawn. 

V. Rejection under 35 U.S.C. § 102(e) 

Applicants traverse the rejection of claims 55-58, 64-68, and 74 under 35 U.S.C. 
§ 102(e) over JVM PI. 

Applicants previously submitted a copy of JVMPI as Appendix A of the 
specification. Further, in patent application no. 09/858,779, which is the parent 
application for the present application, Applicants filed Declarations Under 37 C.F.R. 
§ 1.132 (copies attached), on October 23, 2006 and June 19, 2007, verifying that they 
were the authors of the subject matter in JVMPI. Thus, pursuant to 37 C.F.R. § 716.10, 
JVMPI does not qualify as prior art under 35 U.S.C. § 102(e). Accordingly, the rejection 
of claims 55-58, 64-68, and 74 under 35 U.S.C. § 102(e) should be withdrawn. 

VI. Rejection under 35 U.S.C. § 103(a) 

Applicants traverse the rejection of claims 59-63 and 69-73 under 35 U.S.C. 
§ 103(a) over JVMPI and Tremblay. 

As discussed above, the primary reference, JVMPI, does not qualify as prior art 
because the Applicants are the authors of the subject matter in JVMPI. Thus, the 
Examiner has not established a prima facie case of obviousness using JVMPI and 
Tremblay. Accordingly, the rejection of claims 59-63 and 69-73 under 35 U.S.C. 
§ 103(a) over those references should be withdrawn. 
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VII. Conclusion 

Applicants respectfully request that this Amendment Under 37 C.F.R. § 1 .1 16 be 
entered by the Examiner because it should allow for immediate allowance of the 
pending claims by the Examiner. Further, Applicants submit that the entry of the 
amendment would place the application in better form for appeal, should the Examiner 
dispute the patentability of the pending claims. 

If the Examiner wishes to discuss any aspect of this application, Applicants invite 
the Examiner to contact Applicants' representative undersigned below. 

Please grant any extensions of time required to enter this response and charge 
any additional required fees to Deposit Account 06-0916. 



Respectfully submitted, 



FINNEGAN, HENDERSON, FARABOW, 
GARRETT & DUNNER, LLP. 



Dated: June 30, 2008 




Ketnie Ho 
Reg. No. 51,808 
(202) 408-4287 
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Declaration Under 37 C.F.R. § 1.132 of Sheng Liang 
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I, Sheng Liang, do hereby make the following declaration: 

1 . I authored the document, "Java Virtual Machine Profiler Interface (JVMPI)," 
November 11,1 998 (attached as Appendix A). 

2. To the extent that Appendix A describes the invention(s) in the above-referenced 
patent application, Steffen Grarup and I are the inventors. 

I further declare that all statements made herein of my own knowledge are true and that 
all statements made on information and belief are believed to be true, and further, that these 
statements were made with the knowledge that willful false statements and the like so made are 
punishable by fine or imprisonment, or both, under Section 1001 of Title 18 of the United States 
Code, and that such willful false statements may jeopardize the validity of the application or any 
patent issuing thereon. 



Sir: 



DECLARATION UNDER 37 C.F.R. § 1.132 



Dated: \o/p/ p £> 




Sheng Liang 
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APPENDIX A 



Java Virtual Machine Profiler Interface (JVMPI) 



This document describes ihe Java Virtual Machine Profiler Interface (JVMPI) in JDK 1.2. It is 
intended for tools vendors to develop profilers that work in conjunction with Sun's Java virtual 
machine implementation. 



Contents 

• Overview 

o Start-up 

o Function Call Interface 
o Event Notification 
o JVMPI IDs 

o Threading and Lockine Issues 

o Data Communication between the Profiler Agent and Front-End 

• Interface Functions 

o CreateSvsteroThrcad 

o DisableEvcnt 

o DisablcGC 

o EnableEvent 

o EnableGC 

o GetCallTrace 

o GetCurrentThreadCpuTimc 

o GetMcthodClass 

o GetThreadLocaJStorage 

o GctThreadObiect 

o GctThreadStatus 

o NotifvEvent ~ 

o ProfilerExit 

o RawMonitorCreatc 

o RawMonitorPestroy 

o RawMonitorEnter 

o RawMonitorExit 

o RawMomtorNotifvAll 

o RawMomtorWait 

o RequcstEvent 

o ResumeThread 

o RunGC 

o SetThreadLocalStoragc 
o SuspcndThread 
o ThreadHasRun 



• Events 



c HVMPI EVENT ARENA DELETE 
o JVMPI EVENT ARENA NEW 
o JVMPI EVENT CLASS LOAD 
o JVMPI EVENT CLASS LOA5 H( 




• 
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o JV MPI EVENT COMPILED METHOD LOAD 

o JVMPI EVENT COMPILED METHOD UNLOAD 

o FVMPI EVENT DATA DUMP REQUEST 

o JVMPI EVENT DATA RESET REQUEST 

o JVMPI EVENT GC FINISH 

o JVMPI EVENT GC START 

o JVMPI EVENT HEAP DUMP 

o JVMPI EVENT TNI GLOBALREF ALLOC 

o JVMPI EVENT JNI GLOBALREF FREE 

o JVMPI EVENT JNI WEAK GLOBALREF ALLOC 

o JVMPI EVENT JNI WEAK GLOBALREF FREE 

o JVMPI EVENT JVM INIT DONE 

o JVMPI EVENT JVM SHUT DOWN 

o JVMPI EVENT METHOD ENTRY 

o JVMPI EVENT METHOD ENTRY2 

o JVMPI EVENT METHOD EXIT 

o JVMPI EVENT MONITOR CONTENDED ENTER 

o JVMPI EVENT MONITOR- CONTENDED ENTERED 

o JVMPI EVENT MONITOR CONTENDED EXIT 

o JVMPI EVENT MONITOR DUMP 

o JVMPI EVENT MONITOR WAIT 

o JVMPI EVENT MONITOR WATTED 

o JVMPI EVENT OBJECT ALLOC 

o JVMPI EVENT OBJECT DUMP 

o JVMPI EVENT OBJECT FREE 

© JVMPI EVENT OBJECT MOVE 

o JVMPI EVENT RAW MONITOR CONTENDED ENTER 
o JVMPI EVENT RAW MONITOR CONTENDED ENTERED 
o JVMPI EVENT RAW MONITOR CONTENDED EXIT 
o JVMPI EVENT THREAD END 
o JVMPI EVENT THREAD "START 
Dump Formats 

o Sizes and Types Used in Dump Format Descriptions 
p Heap Dug ip Format 
o Object Dump Fonnat 
o Monitor Dump Fonnat 
Data Types 

o -tcbiectlD 
o JVMPI CallFraroe 
o JVHPI CallTrace 
JVMPI field 



o 


JVMPI 


HeaoDumpAro 


o 


JVMPI 


Lineno 


o 


JVMPI 


Method 


o 


JVMPI 


Re "Monitor 



1. Overview 

The JVMPI is a two-way function call interface between the Java virtual machine and an in-process 
profiler agent On one hand, the virtual machine notifies the profiler agent of various events, 
corresponding to, for example, heap allocation, thread start, etc. On the other hand, the profiler agent 
issues controls and requests for more information through the JVMPI. For example, the profiler agent 
can turn on/off a specific event notification, based on the needs of the profiler front-end. 




20 



; S 

The profiler front-end may or may not run in the same process as the profiler agent. It may reside in a 
different process on the 6ame machine, or on a remote machine connected via the network. The 
JVMPI docs not specify a standard wire protocol. Tools vendors may desigji wire protocols suitable 
for the needs of different profiler front-ends. 

A profiling tool based on JVMPI can obtain a variety of information such as heavy memory 
allocation sites, CPU usage hot-spots, unnecessary object retention, and monitor contention, for a 
comprehensive performance analysis. 

JVMPI supports partial profiling, i.c a user can selectively profile an application for certain subsets of 
the time the virtual machine is up and can also choose to obtain only certain types of profiling 
information. 

In the current version of JVMPI, only one agent per virtual machine can be supported. 

1.1. Start-up 

The user can specify the name of the profiler agent and the options to the profiler agent through a 
command line option to the Java virtual machine. For example, suppose the user specifies: 

java •Xrunayprofilerrheapdump-on, lile«=log. txt ToBeProf iledClass 

The VM attempts to locate a profiler agent library called »yprofiier in Java's library, directory : 

• On Win32, itisSJAVA^HOME\bin\myprofiler.dll 

• On SPARC/Solaris, itTs $JAVA_HOME/lib/sparc/libmyprofiler.so 

If the library is not found in the Java library directory, the VM continues to search for the library 
following the normal library search mechanism of the given platform: 

• On Win32, the VM searches the current directory, Windows system directories, and the 
directories in the path environment variable. 

• On Solaris, the VM searches the directories in ld_libfary_path. 

The VM loads the profiler agent library and looks for the entry point: 

jint JUICAL1* JVM_OnLoad(JoveVM *jvm, char ^options, void *reserved); 

The VM calls the jVM_onLoad function, passing a pointer to the Jav&VM instance as the first 
argument, and string "heapdump«=on, i ile-=iog . txt ■ as the second argument. The thiTd argument to 
JVH_ontoad is reserved and set to null. 

On success, the jvu_onL©ad function must return jni_ok. If for some reason the JVM_Oni>oad 
function fails, it must return JNIJERR- 

1.2. Function Call Interface 

The profiler agent can obtain a function call interface by issuing a Get Env call on the Java vm pointer. 
For example, the following code retrieves the version of JVMPI interface that is implemented in JDK 



1.2: 



JVMPJInter £ace • j vmpi_inter i ace ; 

JNIEXPORT jint JNICAJLL JVM_OnLoad(JavaVM % jvm, char 'options, void 'reserved) 
( 

int res - ( * jvm) ->GetEnv < j vro, (void * * > &jvmpi_inter f ace, JVMPi_VERSION 1) 
if (res < 0) | 

return JN1 ERR; 

) ' ' 

... /* use entries in jvmpi_interf ace */ 

I 

The JvMPi_interfoce structure defines the function call interface between the profiler agent and the 

VM: 

/♦ interface functions V 
typedet struct ( 

jint version; /* JVMPI version */ 

/• — interlace implemented by the profiler '/ 

void (' Notif vEvent ) (JVMPI Event 'event) ; 

/♦ interface implemented by the JVM '/ 

jint ('EnableEvcntl Hint event_type. void *arg) ; 
jint (' PisableEvent ) Hint event_type, void 'arg) ; 
j4nt l^ ReguestEvent ) tiint event_type # void *arg) ; 

void t^ GetCallTrace ) ( JVMPIJTa 11 Trace 'trace, jint depth); 

void C ProfilerExit ) Hint): 

JVMPI_RawMonitor ( ♦ RawMonitorCreate ) (char 'lock name); 

void i ' RawMonitorEnter ) < JVMPI_RawMonitor lock_id) ; 

void C RawMonitorExit ) ( JVMPI_RawMonitor lock_id) ; 

void C RawMonitorWalt ) (JVMPI RawHonitor loek_id, jlong ros); 

void ( • Ra wMon i t or Hot i f vAl 1 ) ( JVMPI_RawMonitor lock_id) ; 

void (' RawMonltorDestrov l ( JVMPI_Ra wMon 1 1 or lock_id) ; 



jlong CGetCurrentThreadCpuTime) (void) .- 
void CSuspendThread) (JKIEnv *env) ; 
void (- ResumeThread l (JKIEnv *env) ; 
jint (' GetThreadStatus l (JKIEnv *env) ; 
jboolean C ThreadHasRun ) (JNIEnv *env); 

jint t' CreateSvstemThread ) (char 'name, jint priority, void ('f ) (void ')); 
void C SetThreadLocalStoraoe ) (JNIEnv *env id, void *ptr) ; 
void * CGetThreadLocalStoraae) (JWIEnv 'env_id) ; 

void C DisableGC ) (void): 
void (' EnableGO (void): 
void CEaziSS) (void) ; 

jobjectID CGetThreadObSect) (JNIEnv *env); 
jobjectID («Ge$Methodc;iag;0 ( jmethodID mid); 
) JVMPI Interface; 



The Get Env function returns a pointer to a jvmpi interface whose version field indicates a 
JVMPI version that is compatible to the version number argument passed in the Get Env call. Note 
that the value of the version field is not necessarily identical to the version argument passed in the 
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CetEnvcall. 



The jvmpi inter lac* returned by CctEnv has all the functions set up except for Not if yEvcnt. The 
profiler agent must set up the Noti f yEvent function pointer before reluming from Jv M _onLoad. 

1.3. Event Notification 

The VM sends an event by calling NotifvEvent with a Jv M pi_Ev*nt data structure as the argument. 
The following events arc supported: 

• method enter and exit 

• object alloc, move, and free 

• heap arena create and delete 

• GC start and finish 

• TNI global reference alloc and free 

• TNT weak global reference alloc and free 

• compiled method load and unload 

• thread start and end 

• class file data ready for instrumentation 

• class load and unload # 

• contended Java monitor wait to enter » entered , and exit 

• mntended raw monitor wait to enter, entered , and exit 

• Java monitor wait and waited 

• monitor dump 

• heap dump 
object dump 



request to dump or reset profiling data 
Java virtual machine initialization and shutdown 



The jVMFi_Event structure contains the event type, the JHiEnv pointer of the current thread, and 
other event-specific information. The event specific information is represented as a union of event- 
specific structures. The JVMPI Events section provides a complete description of all event-specific 
structures. For now, we show the event-specific structures for class load and class unload below. 

typedef struct { 

jint event_type; /• event_type */ 

JNIEnv *env_id; /* «" v where this event occurred ♦/ 

union { 

struct t 

char *class name; /* class name */ 

char *source_name; /* name of source file */ 

jint num interfaces; /* number of interfaces implemented ♦ 

jint nunTrnethods; /* number of methods in the class */ 

jvmpi Method •methods; /* methods ♦/ 

jint num static fields; /* number of static fields */ 

JVMPI Field 'statics; /* static fields */ 

jint num_instance_fields; /* number of instance fields */ 

JVMPI_Field 'instances; /* instance fields */ 

jobjectID classed; /* id of the class object */ 
) class_load; 

struct < 

jobjectID class_id; /* id of the class object */ 

) class unload; 



... /• Refer to the section on JVMPI events for a full listing V 

) u; 



# • 
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) JVMPI_Ev«nt; 
1.4. JVMP1 IDs 

The JVhfPI refers lo entities in the Java virtual machine as various kinds of IDs. Threads, classes, 
methods, objects, heap arenas and JNI global references all have unique IDs. 

Each ID has a defining event and an undefining event. A defining event provides the information 
related to an ID. For example, the defining event for a thread ID contains, among other entries, the 
name of the thread. 

An ID is valid until its undefining event arrives. An undefining event invalidates the ID. whose value 
may be reused later as a different kind of ID. The value of a thread ID, for example, may be redefined 
as a method ID after the thread ends. 



ID 

thread to 


data type | 
JHIEnv * | 


defining event 
thread start | 


an defining event | 
thread end 


oEjectID 


jobject I Dj 


object alloc | 


obiect Iree, obiect move, and arena delete] 


class ID' 


jobjectlD) 


class load | 


class unload and obiect move j 


method ID 


jroethodlD] 


defining class load] 


defining class unload | 


arena ID 


jint 


arena new jjarena delete ~~| 


JNI global rel li) 


j object 


global ret alloc J|Rlobal ref tree 



Assuming the defining events are enabled during the profiler initialization, the profiler agent is 
guaranteed to be notified of an entity's creation through a defining event, before the entity appears in 
other JVMPI events. 

If the defining events are not enabled, the profiler agent may receive an unknown ID. In that case the 
profiler agent may request the corresponding defining event to be sent on demand by issuing a 
RequcstEvent call. 

IDs representing objects have type i object ID . A class is represented by the object ID of the - 
conesponding java .lang. class object Therefore, class IDs are also of type jobj.ectlD. 

A j ob j ect id is defined by an object alloc event, and remains valid in the arena in which the object is 
allocated until one of its undefining events arrive: 

• Aii obiect free event invalidates an object ID. 

• An obiect move event is a special type of undefining events. Unlike other undefining events 
which signal the cnd-of-life of the corresponding entities, the object still exists, but its ID 
changes, and it may have been moved to a new arena. 

• An arena delete event invalidates all remaining object EDs in the arena. 

When an object free or arena delete event invalidates an object ID, the object is known as being 
garbage collected. 

Typically, the profiler agent maintains a mapping between j object ids and its internal representation 
of object identities, and updates the mapping in response to the defining and undefining events for 
JVMPI object IDs. 

Since object IDs may be invalidated during GC, the VM issues all events that contain jobjectlD 
entries with GC disabled. In addition, the profiling agent must disable GC when it is directly 
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manipulating any j object ID data types. Otherwise the GC may invalidate a j object id while it is 
being manipulated in the agent code. The profiler agent must make sure that GC is disabled when it 
caJls a JVMPI function that either lakes a jobject id argument or returns a jobjectiD result If the 
function call is inside an event handler where GC is already disabled, then the profiler agent need not 
explicitly disable the GC again- 

A thxead may be identified either by its JMEnv interface pointer or by the object ID of the 
corresponding jovc . l*ng . Thread object. The JNIEnv pointer is valid between thread start and 
thread end events, and remains constant during the lifetime of a thread. The j eve. lang .Thread 
object ID, on the other hand, could remain valid after the thread ends, until it is garbage collected. 
The profiler agent can convert a JNIEnv pointer to the corresponding thread object ID by calling the 
GetThreadObjgct function. 

1 .5. Threading and Locking Issues 

The JVMPI is used by the profiler agent that runs in the same process as the Java virtual machine. 
Programmers who write the agent must be careful in dealing with threading and locking issues in 
order to prevent data corruption and deadlocks. 

Events arc sent in the same thread where they are generated. For example, a class loading event is 
sent in the same thread in which the class is loaded. Multiple events may arrive concurrently in 
different threads. The agent program must therefore provide the necessary synchronization in order to 
avoid data corruption caused by multiple threads updating the same data structure at the same time. 

In some cases, synchronizing on certain frequent events (such as method entry and method exit) may 
impose unacceptable overhead to program execution. Agents may utilize the thread-local storage 
support provided by the JVMPI to record profiling data without having to contend for global locks, 
and only merge the thread-local data into global profiles at selected intervals. The JVMPI supplies 
the agent with a pointer-size thread-local storage. Following is a simple example that illustrates how 
a profiler agent may take advantage of this feature. Suppose we need to write a profiler agent that 
counts the number of methods executed in each thread. The agent installs event handlers for thxead 
start, method entry, and thread end events: 

/* thread start event handler 

* sets up the storage lor thread-local method invocation counter 
*/ 

void ThreedStartHandler (JNIEnv *thread_id) 
t 

int *p ctr ~ (int * )malloc (sizeof (int ) ) ; 

CALL (SetThreadLocalStorage ) (thread id, p_etr) ; 

) . 

/• method enter event handler 

* increments thread local method invocation counter 
•/ 

void MethodEntryHandler ( jmethodID method_id/ JNIEnv ^thread id) 
< 

int # p ctr « (int * ) CALL (GetThreadLocalStorage) (thread id) ; 
(*p ctr)**; 

) 

/* thread end handler 

* prints the number of methods executed 
♦/ 

void ThreadEndHandlert JNIEnv * thread id) 
( 

int *p_ctr « (int * ) CALL (GetThreadLocalStorage) (thread id) ; 
rprint?(stdout, ^Thread %x executed %d methods^". 
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threaded, (*p_ctr)); 
free (p ctr) ; 

) - 

The following JVMPI functions can cause event notification to be sent synchronously in the same 
thread during the function execution: 

• RequestEvent 

• CreateSvstcmThread 

• RungC 



The RequestEvent function supplies the JVMPI event explicitly requested by the profiler agent. The 
CieeteSystemThread function causes thread object allocation and thread start events to be issued. 
The RunGC function causes GC-related events to be generated. 

When a profiling agent is loaded into the Java virtual machine,, the process can cither be in one of 
three modes: multi-threaded mode with GC enabled, multi-threaded mode with GC disabled, and the 
thread suspended mode. Different JVMPI events are issued in different modes. Certain JVMPI 
functions change the process from one mode to another. 

The profiler agent must obey the following guidelines to avoid deadlocks: 

• In the multi-threaded mode with GC enabled, the agent code has a great deal of freedom in 
acquiring locks and calling JVMPI functions. Of course the normal rules of deadlock 
avoidance apply. Different threads must not enter the same set of locks in different orders. 

• When the GC is disabled the agent program must not call any JVMPI function that could 
require new Java objects to be created or cause the garbage collector to run. Currently, such 
functions include createSystemThread and RunGC. In addition, programmers need to be 
aware that disabling the GC creates an implicit locking dependency among threads. When the 
GC is disabled, the current thread may not be able to safely acquire certain locks. Deadlocks 
may happen, for example, if one thread disables GC and tries to acquire a lock, while another 
thread already acquired that lock but is triggering a GC. 

• In the thread suspended mode, one or more of the threads have been suspended. In this case, 
the agent program must not perform any operations that may cause the current thread to block. 
Such operations include, for example, the malloc and f printf functions provided by the 
standard C library. These functions typically acquire internal C library locks that may be held 
by one of the suspended threads. 

1.6 Data Communication between the Profiler Agent and Front-End 

The JVMPI provides « low-level mechanism for a profiler agent to communicate with the virtual 
machine. The goal is to provide maximum flexiblity for the profiler agent to present the data 
depending on the needs of the front-end. and also to keep the processing work done by the virtual 
machine at a minimum. Therefore, the JVMPI docs not specify a wire protocol between the profiling 
agent and the front-end. Instead, tools vendors design their own profiling agents that suit the needs of 
their front-ends. 

The following issues need to be considered when designing the wire protocol in order to allow the 
profiler agent and front-end to reside on different machines: 

• Pointer size (e.g.. 32 or 64 bit) - all of the JVMPI IDs are of pointer type (see Data Types) . 

• Byte order (little endian or big endian). • 

• Bit order (most significant bit first or least significant bit first). 
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. Siring encoding - the JVMP1 uses the UTF-8 encoding as documented in Ihe Java virtual 
machine specification. 

For example, the hprof profiler agent shipped with JDK 1 .2 sends the size of all IDs as the first 
record, and uses the standard network byte order for integer and floating-point data. 

2. Interface Functions 

jint («Creat*SysO*n»Thread> (char «nwc ( jint priority, void (*f ) (void •)); 
Called by the profiler agent to create a daemon thread in the Java virtual machine. 

It is safe for the profiler agent to make this call only after the JVM notifies a 

jvmpi evznt_init_done and when the system is in a multi-threaded mode with GC enabled. 

Arguments: 

name - name of the thread. 

priority- thread priority; the values can be: 

JVMPI_NORMAL_PRI0RITY 

JVMPI_MAXlMUM_PRIORITY 

JVMPI_MINIMUM_PRIORlTY 

f - function to be run by the thread. 

Returns: 

jni_ok - success- 
JNI_ERR • failure. 

jint (♦DisableEvent) (jint event_type, void *are/) ; 

Called by the profiler agent to disable the notification of a particular type of event Apart from 
event type, the profiler agent may also pass an argument that provides additional information 
specific to the given event type. 

All events are disabled when the VM starts up. Once enabled, an event stays enabled until it is 
explicitly disabled. 

This function returns JVMPI_NOT_AVAiLA£LE if event_type is JVWPI_EVENT_HEAP_DOMP, 
JVMPI_E VENT_MON I TOR_DUMP orJVMP I JEVENT_OB JXCT_DUMP . 

Arguments: 

event_type - type of event, JVMPI_EV£OT_CLASS_LOAD etc. 
arg - event specific information- 

Returns: 



• it 
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jvmp j _ success disable succeeded. 

jvmpi^FAIL disable failed. 

jv^'not available disabling the given event_typ c is not 

- - - available. 

void <*DisabloGC) (void) ; 

Called by the profiler lo disable garbage collection, until EnabiedGC is called. DisableGC and 
EnableGC calls may be nested. 

jint (•EnableEvent) (j in t even retype; void~*arg) ; 

Called by the profiler agent to enable notification of a particular type of event. Apart from 
event type, the profiler may also pass an argument that provides additional information 
specific to the given event type. 

All events arc disabled when the VM starts up. Once enabled, an event stays enabled until it is 
explicitly disabled. 

This function returns Jvmpi_not_AVAILABLE if event_type is JVMPI_EVENT_HEAP_DUMP, 
jv74P1_event_monitor_dump or"jVMPI_EVENT_OBJECT_DUMP. The profiler agent must use the 
RequestEvent function to request theseevents. 

Arguments: 

event_type - type of event, jvmpi_event_class_i;oad etc. 
arg - event specific argument. 

Returns: 

jvwpi_success enable succeeded. 

jvmpijtail enable failed. 

JVMPI.NOT^AVAIIABLE JSJJgJ* """^ &C ~ t ^ W IS not 

void <*EnableGC) (void) ; 

Enables garbage collections. DisableGC and EnableGC calls maybe nested. 

void <*GetCallTraee) i JVMPXCallTrace 'trace, jint depth) ; 

Called by the profiler to obtain the current method call stack trace for a given thread. The 
thread is identified by the env_id field in the jvmpi CallTrace structure. The profiler agent 
should allocate a jvmpi Call Trace structure with enough memory for the requested stack 
depth. The VM fills in the frames buffer and the numjrames field. 

Arguments: 

trace - trace data structure to be filled by the VM, 
depth - depth of the call stack trace. 
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jlong (*Cct:CurrtontThxo»dCpuTittw) (void) ; 

Called by the profiler agent to obtain the accumulated CPU lime consumed by the cuncnt 
thread. 

Rerurns: 

time in nanoseconds 

•i object ID f •GetWethodClass) (3»ethodTD mid) ; 

Called by the profiler agent to obtain the object ID of the class that defines a method. 

The profiler must disable GC before calling this fiinction. 

Arguments: 

mid - a method ID. 
Returns: 

object DD of the defining class. 

void • ( *CetThreadLocal Storage ) (JNXEiw *env_id) ; 

Called by the profiler to get the value of the JVMPI thread-local storage. The JVMP1 supplies 
to the agent a pointer-size thread-local storage that can be used to record per-thread profiling 
information. 

Arguments: 

en v id - the JNiEnv * of the thread. 
Returns: 

the value of the thread local storage 

-iob-iectlD (•GetThreadObjeet) (JNXEnv »env) ; 

Called by the profiler agent to obtain the thread object ID that corresponds to a JNiEnv pointer. 

The profiler must disable GC before calling this function. 

Arguments: 

env - JNIEnv pointer of the thread. 
Returns: 
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ihe thread object ID. 

jant ( ♦CtttThroadStat'Ut) (JKIEnv •envj ; 

Called by the profiler agent to obtain the status of a thread. 

The JVMPI functions SuspendThread and ResumeThread have no affect on the status returned 
by GetThreadStatus. The status of a thread suspended through the JVMPI remains unchanged 
and the status at the time of suspension is returned. 

Arguments: 

env - the JNlEnv • of the thread. 
Returns: 

. JVMPI JTHR£AD_run>i able - thread is mnnable. 
jvmpi_thri^_monitor_wait • thread is waiting on a monitor. 
Jvmpi JTHREAD_condvak_wait - thread is waiting on a condition variable. 

When a thread is suspended (by j a va.lang. Thread. suspend) or interrupted in 
any of the above states the jvmpi_thread_sus PENDED or the 
JVMPI_THREAD_INTERRUPTED bitls set 

void ( *Noti-f yXven t) (JVHPI_Event * event) ; 

\ . 

Called by the VM to send an event to the profiling agent The profiler agent registers the types \ 
of events it is interested in by calling EnableEvent . or requests a specific type of event by J 
calling RequeatEvent . J 

When an event is enabled by EnableEvent, the thread that generates the event is the thread in 
which the event is sent When an event is requested by Request Event, the thread that requests 
the event is the thread in which the event is sent Multiple threads may send multiple events 
concurrently. 

If the event specific information contains a j object ID, this function is called with GC 
disabled. GC is enabled after the function returns. 

The space allocated for the JVMPl_Event structure and any event specific information is freed 
by the virtual machine once this function returns. The profiler agent must copy any necessary 
data it needs to retain into its internal buffers. 

Arguments: 

event - the JVMPI event sent from the VM to the profiling agent. 

void ('PxofilerExit) (jint err^code) ; 

Called by the profiler agent to inform the VM that the profiler wants to exit with error code set 
to err_code. This function causes the VM to also exit with the same err_code. 
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Arguments 

err code - exit code 
JVMPI RavMoni tor ( # RnwMonitorCreato) (chax *lock_name) ; 

Called by ihc profiler to create a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
this function may call arbitrary system functions such as melloc and block on an internal 
system library lock. 

If the raw monitor is created with a name beginning with an underscore (•_•)• then its monitor 
contention events arc not sent to the profiler agent. 

Arguments: 

lock_name - name of raw monitor. 
Returns: 

a raw monitor 

void (TRavMonitorDestroy) ( JVMPI RawMonitor lock_£d) ; 

Called by the profiler agent to destroy a raw monitor and free all system resources associated 
with the monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
this function may call arbitrary system functions such as free and block on a internal system 
library lock. 

Arguments: 

lock_id - the raw monitor to be destroyed 

void (*RawMonitor£nter) ( JVMPI_RavMoni tor lock_id) ; 

Called by the profiler agent to enter a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
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the current thread may block on the raw monitor already acquired by one of the suspended 
threads: 

Arguments; 

locfc_id- the raw monitor to be entered 

void (*Ra»Moni tor Exit) i JVMPlRawMoni t or lock^id) ; 

Called by the profiler agent to exit a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

lock_id - the raw monitor to exit 

void (*RawMonitorKotifyAll) (JVMPI RavMonitor loek__id) ; 

Called by the profiler to notify all the threads that are waiting on a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

lock_id - the raw monitor to notify 

void <»RavMonitorWait) ( JVMPI_fta*Monltor loek_±d, jlong as); 

Called by the profiler agent to wait on a raw monitor for a specified timeout period. Passing 0 
as the timeout period causes the thread to wait forever. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

iock_id - the raw monitor to wait on 
ms - time to wait (in milliseconds). 

jint. (*B«questEvent) (jint event_type, void *arg) : 

Called by the profiler agent to request a particular type of event to be notified Apart from 
event type, the profiler agent may also pass an argument that provides additional information 
specific to the given event type. 

This function can be called to request one-time events such as jvmpi event heap dump, 
jvmpi_event_moni tor dump and Jvmpi_evxnt_object_dump. NotHjcatioiTfor these events 
cannot be controlled by the EnableEvent and DisabieEvent functions. 
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In addition, this function can be called to request the defining events for a specific class, 
thread, or object. This is useful when the profiler agent needs to resolve an unknown class, 
method, thread, or object ID received in an event, but the corresponding defining event was 
disabled earlier. 

• The profiler agent may receive information about an unknown class CD by requesting & 
jvmPI EVENT CLASS load event and setting the event-specific argument to the class 
object ID. . ' 

• The profiler agent may receive information about an unknown thread ID by requesting a 
jvmpi event THREAD START event and setting the event-specific argument to the thread 
object ED. 

• The profiler agent may receive information about an unknown object ID by requesting a 
JVMPI EVENT OBJECT alloc event and setting the event-specific argument to the object 
ID. 

Thus the profiler agent can cither enable the above three events asynchronously by calling 
Enablement , or request these events synchronously by calling Request Event . The requested 
event is sent in the same thread that issued the Request Event call, and is sent before the 
RequestEvent function returns. 

The RequestEvent function cannot be used to request other events not listed above. 

Events requested through RequestEvent will arrive with the JVMPI_REQUESTED_EVENT bit set 
in its event_type. 

Arguments: 

event_type - type of event, JVMPI_EVXNT_CLASS_LOAD etc. 
arg - event specific argument. 

Returns: 

JVMPI_SUCCESS request succeeded. 

jvmpi_FAIL request failed 

JVMPlIwT.AVAXXABLB ^SS^ ^ ~ent_t»e " *Ot 

void (*ResumeThx«ad) (JHIEnv *env) ; 

Called by the profiler agent to resume a thread 

Note that a thread suspended by the java. lang. Thread, suspend method cannot be resumed 
by.the JVMPI ResumeThread function. 

Arguments: 

env - the ONiEnv • of the thread. 

void (*RunCC) (void) ; 

Called by the profiler to force a complete garbage collection. This function must not be called 
when GC is disabled. 
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void ( *SHt Thi*adLocalStorac>«f) (JNIXnv *cnv_id, void *ptr) ; 

Called by the profiler agent to set the value of the JVMPI thread-local storage. The JVMPI 
supplies to the agent a pointer-size thread-local storage that can be used to record per-thread 
profiling information. 

Arguments: 

env_id - the JNIEnv * of the thread. 

pt r - the value to be entered into the thread-local storage. 

void (*SuapeTidThr©ed) (JNIEnv ««nv) ; 

Called by the profiler agent to suspend a thread. The system enters the thread suspended mode 
after this fiincrion is called. 

Note that a thread suspended by the JVMPI SuspendThread function cannot be resumed by the 

java . l&ng .Thread. resume method. 

In the JDK 1 2 implementation, this function must be called when the GC is disabled. GC must 
remain disabled until all threads have been resumed. 

Arguments: 

env -the JNIEnv * of the thread. 

j boolean (*ThreadHasK\in) (JNIEnv *env) ; 

Called by the profiler to determine if a thread identified by the given JNIEnv pointer has 
consumed CPU time since the last time the thread was suspended by SuspendThread . This 
function must be called when the thread has been resumed by ResumcThrcad and then 
suspended again by the SuspendThread function. 

Arguments: 

env - the JNIEnv * of the thread. 
Returns: 

jni_troe - thread got a chance to run. 
jni_FALSE - thread did not get a chance to run. 

3. Events 

JVMPI_iraNT_«ENA_I)EIXTE 

Sent when a heap arena is deleted. 

All objects residing in this arena are freed. An explicit jvhpi event object free is not sent 
for those objects. The profiler agent can infer all the objects currently residing in that arena by 
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keeping track of the object allocations in the arena and all the objects moved in and out of th< 
arena. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via meiioc) 

This event is always sent between a pair of jvmpi event gc START and 

jvmpi event GC finish events. The proGlcr agent should acquire all the locks need for 

processing this event in the event handler for Jvmpi_EVENT_gc_START. 

struct ( 

jint arena^id; 
) delete_arene; 

Contents: 

aren*_id - ID of the arena being deleted. 

JVMPIJEVXNT_AR£HA_NEV 

Sent when a new arena for allocating objects is created. 

struct ( 

jint arena_id; 

char *arena_narae; 
) new^arena; 

Contents: 

arena_id - ID given to the arena. 
arena_nanie - name of the arena. 

jvmpi_evxkt_class_load 

Sent when a class is loaded in the VM, or when the profiler agent requests a 
JVMPI_EVENT_ciass_load event by issuing a RequestEvent call. In the latter case, the 
jvmpi^REquested^event bit in the event type is set. 

This event is issued with GC disabled. GC is re-enablcd after NotifvEvent returns. 

struct { 

char *class_naiue; 

char *source_namef 

jint num_interf aces; 

jint nun methods; 

JVMPI Method ^methods; 

jint num static fields; 

JVMPI_Field 'statics; 

jint num instance fields ; 

JVMPI Field 'instances; 

jpfrjectJTp elassJLd; 
) class_load; 



Contents: 
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class^name - name of class being loaded. 

5ouicc_najne - name of source file thai defines ihc class. 

num_interf aces - number of interfaces implemented by this class, 
methods - methods defined in the class. 

num_jtotic_f ieid* - number of static fields defined in this class, 
statics - static fields defined in the class. 

num_instanc*_f ields - number of instance fields defined in this class, 
instances - instance fields defined in the class. 

ciass_id - class object DO. 

Note: class IDs are IDs of the class objects and are subject to change when 
JVMPI_EVENT_OBJECT_M0VE arrives. 

OVKP l_Jtt NT_CL*S S_UOAD_HOOK 

Sent when the VM obtains a class file data, but before it constructs the in-memory 
representation for that class. The profiler agent can instrument the existing class file data sent 
by the VM to include profiling hooks. 

The profiler must allocate the space for the modified class file data buffer using the memory 
allocation function pointer sent in this event, because the VM is responsible for freeing the new 
class file data buffer. 

struct { 

unsigned char *class_data; 

jint cla3s_data_len; 

unsigned char *new_class_data; 

jint new_class_data_len; 

void * (*malloc_f) (unsigned int); 
) class_load_hook; *" 

Contents: 

class_data - pointer to the current class file data buffer. 

class_data_len - length of current class file data buffer. 
new_class_data - pointer to the instrumented class file data buffer. 
new_class_data_len - length of the new class file data buffer. 
maiioc_f - pointer to a memory allocation function. 

The profiler agent must set n«w_ciass_data to point to the newly instrumented class file data 
buffer and set new_class data_len to the length of that buffer before returning from 
NotifyEvent . It must setT>oth neu_claiss_data and new_class_data_Ien to the old values if 
jt chooses not to instrument this class. 

JVMPI_rVEHT_CXAS S_UNIiOAD 

Sent when a class is unloaded. 

This event is issued with GC disabled. GC is re -enabled after Wot ifyE vent returns. 
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struct I 

jobicct ID clasaid; 
) ciass_unload; 

Contents: 

classed - class being unloaded. 

JVMPI E VENT_COMP I UED__ME THOD_l>QAD 

Sent when a method is compiled and loaded into memory. 

struct ( 

jmethodID method_id; 

void •code_addr; 

jint code_size; 

jint lineno_table_size; 

JVMPI_Lineno *lineno_teble; 
) compiled_method_load; ~~ 

Contents: 

method_id - method being compiled and loaded. 

•code_addr - address where compiled method code is loaded. 

code_size - size of compiled code. 
lineno_table_si ze - size of line number table. 

_ , . . . - table mapping offset from beginning of method to the sre 

lin«no_table file line number. 

JVMPIJEVEOT jCCWIIXD_HETHOTJUNM*D 

Sent when a compiled method is unloaded from memory. 

struct ( 

jmethodID method^ id; 
) compi.led_method_unload; 

Contents: 

method_id - compiled method being unloaded. 

0VHP2JEVENT_DATA_DUMP_REQUEST 

Sent by the VM to request the profiler agent to dump its data. This is just a hint and the profiler 
agent need not react to this event This is useful for processing comm and line signals from 
users. For example, in JDK 12 a CTRL-Break on Win32 and a CTRLA on Solaris causes the 
VM to send this event to the profiler agent 

There is no event specific information. 

JVMPI EVENTED ATA_R£ SE T_R£QUE 6 T 



m 
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Sent by ihc VM to request the profiler agent to reset its data. This is just a hint and the profiler 
agent need not react to this event. This is useful for processing command line signals from 
users. For example, in JDK 1 .2 a CTRL-Brcak on Win32 and o CTRLA on Solaris causes the 
VM to send this event to the profiler agent. 

There is no event specific information. 

JVMPIEVENTGCFINI SH 

Sent when GC finishes. The profiler agent can release any locks, grabbed during GC start 
notification for handling object free, object move, and arena delete events. The system gets 
back into the multi-threaded mode after this event. 

The event-specific data contains Java heap statistics. 

struct ( 

jlong used_objects; 

jlong used object_space; 

jlong totaT_object_space; 
) gc_info; 

Contents: 

used_objects * number of used objects on the heap. 

used_ob j ect_space - amount of space used by the objects (in bytes). 

total_object_space - total amount of object space (in bytes). 

JVMPI_rVEOT_GC_STARX 

Sent when GC is about to start. The system goes into thread suspended mode after this event, 
to avoid deadlocks, the profiler agent should grab any locks that axe needed for handling 
object free, object move, and arena delete events in the event handler for this event 

There is no event specific information. 

JVKPI^rVEKT^KEAP^DUKP 

Sent when requested by the RequeatEvent function. The profiler agent can specify the level of 
information to be dumped by passing an Jvhpi HeapDumpAro structure to Request Event as 
the second argument, with the heap_dump_level field set to the desired dump level. 

The dump level values can be one of the following: 

• JVHPI_DUMP_LEVEL_0 

• JVMPI_DaMP_LEVEL_l 

• JVMPX_DUMP_LEVEL_2 

If a NULL value is passed, then the dump level is set to Jvmpi_dump_LEvel_2. 
This event is issued with GC disabled. GC is re-enabled after NotifvEvent returns. 
The event-specific data contains a snapshot of all live objects in the Java heap. 
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struct { 

int dump_level; 

char *begin; 

char *end; 

jint nuro_traces; 

JVMPX CallTrace "traces; 
J heap_dump; 

Contents: 

dump_level - the dump level specified in ReguestEvent 
begin - beginning of the heap dump 
end - end of the heap dump 

- number of stack traces in which the GC roots reside, 0 for 
nun - t rac " JVMPI J5UMP J-EVELJ) 
traces - the stack traces in which the GC roots reside 

The format of the heap dump between begin and end depends on the level of information 
requested. The formats are described in detail in the JVMPI Dump Formats section. 

jvmpi_event_jni_globaiju:f_aijloc 

Sent when a JNI global reference is created. The event-specific data contains the JNI global 
reference as well as the corresponding object ID. 

This event is issued with GC disabled. GC is re-cnabled after NotifvEvent returns. 

struct ( 

iobiectJD obj_id; 

j ob j ect refold ; 
) jni_globalref^alloc; 

Contents: 

obj_id - object ID referred to by the global reference. 
ref_id - JNI global reference. 

JVMPI_EVBKT_JNIjCI-OBAliREF_FREE 

Sent when a JNI global reference is deleted. The event-specific data contains the JNI global 
reference that is being deleted. 

struct { 

jobject ref_id; 
} jni_globalref~f ree; 

Contents: 

ref _id - JNI global reference. 

JVKPI rVENT_JNI_WI^_GIiOBAlJ<ZF_AI^CX: 
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Sent when a JN1 weak global reference is created. The event-specific data contains the JN1 
weak global reference as well as the corresponding object ED. 

This event is issued with GC disabled: GC is re-enabled after Hoti f vEvcnt returns. 

struct { 

i object IP obj_id; 

jobject ref_id; 
) jni_globalref_alloc; 

Contents: 

obj_id - object ID referred to by the weak global reference. 
ref_id - JN1 weak global reference. 

JVMPI_EVEKT_^ JNI_WEAK_CIOBAXJ<E F_FREE 

Sent when a JNI weak global reference is deleted. The event-specific data contains the JN1 
weak global reference that is being deleted. 

struct ( 

jobject ref^id; 
) jni_globalref~f ree; 

Contents: 

re f _i d - JNI weak global reference. 

JVMPI_EVEOT_JVM_ INITJJONE 

Sent by the VM when its initialization is done. It is safe to call CreateSystemThread only 
after this event is notified 

There is no event specific data. 

JVMPIJEVXKT_JVM_SinJX_t)OWN 

Sent by the VM when it is shutting down. The profiler typically responds by saving the 
profiling data. 

There is no event specific data. 

JVMPIJEVENTJMETHOD_ENTRY 

Sent when a method is entered. Compared with jvmpi_event M£TH0D_entry2, this event does 
not send the jobject id of the target object on which the method is invoked. 

struct ( 

j method ID method_id; 
) method; 

Contents; 



40 



met hod_id - the method being entered. 

JVMPI_EVENTJffiTHODJ£NTR« 

Sent when a method is entered. If the method is an instance method, the 1 object IP of the 
target object is sent with the event. If the method is a static method, the obj_id field in the 
event is set to NULL. 

This event is issued with GC disabled. GC is re-enabled after Hotxt vEvent returns. 

struct f 

jmethodID method ad; 

lobjgctlP obj_id7 
) method_entry2; 

Contents: 

met hod_id - the method being entered. 

obj_id • the target object, null for static methods. 

JVMP I_E VE NT_ME THOD_EXI T 

Sent when a method is exited. The method exit may be a normal exit, or caused by an 
unhandled exception. 

struct { 

jmethodID method_id; ' 
) method; 

Contents: 

method_id - the method being entered. 

JVMP I_E VENT_MON I TOR_CONTENDE D_ENTER 

Sent when a thread is attempting to enter a Java monitor already acquired by another thread. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct M 

iobiectID object ; 
) monitor; 

Contents: 

ob j ect - object ID associated with the monitor 

JVMP I_FVEHT_MONI T OR_CONTEHDED_ENTER£D 

Sent when a thread enters a Java monitor after waiting for it to be released by another thread. 
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This event is issued with GC disabled. GC is re-enabled after NotiivEvcnt returns, 
struct ( 

iobiect ID object; 
) monitor; 

Contents: 

object - object ID associated with the monitor 

JVMP 1_E VENTJ4DN I TOR_CONTEOTED_EXI T 

Sent when a thread exits a Java monitor, and another thread is waiting to acquire the same 
monitor. 

This event is issued with GC disabled. GC is re-enabled after NotifvBvent returns. 

struct { 

jobjffcUP object; 
) monitor; 

Contents: 



obj ect - object ID associated with the monitor 

JVMPIJTV^NT_MOHIIOR_pUMP 

Sent when requested by the RgguestEvcnt function. 

The event-specific data contains a snapshot of all the threads and monitors in the VM. 
This event is issued with GC disabled, GC is re-enabled after NotifyEvent returns. 

struct ( 

char *begin; 

char *end; 

jint num_t races; 

<TVffi>;i,CallTrace * traces ; 

jint *threads_ status ; 
> monitor_duinp; 

Contents: 

begin - start of the monitor dump buffer 

end - end of the dump buffer 

num_traces - number of thread traces, 
traces - traces of all threads. 

thread_stacus - status of all threads. 

The format of the monitor dump buffer is described in detail in the JVMPI Dump Formats 
section. 
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JVKPI EVENT_MON I TOR_WAl T 

Sent when a thread is about to wait on an object. 

This event is issued with GC disabled. GC is rc-cnabled after Not ifvEvent returns. 

struct r 

S obi ect ID object; 

jlong timeout; 
) mbnitor_wait ; 

Contents: 

ob j ect - ID of object on which the current thread is going to wait. 

(NULL indicates the thread is in Thread. sleep.) 

- the number of milliseconds the thread will wait (0 indicates waiting 
timeout forcvcr ) 

JVMPI_rVENT_MDNI TOR^WAI TED 

Sent when a thread finishes waiting on an object. 

This event is issued with GC disabled. GC is re-enabled after NotiryEvent returns. 

struct { 

jpMectilD object; 

jlong timeout; 
) monitor_wait ; 

Contents: 

object . - ID of object on which the current thread waited. 

(null indicates the thread is in Thread, sleep.) 
timeout - the number of milliseconds the thread waited. 

JVMPI_EV£NT_OBJECT_ALLOC 

Sent when an object is allocated, or when the profiler agent requests a 
jvmpi_event_obJECT_alloc event by issuing a RequestEvent call. In the latter case, the 
jvmpi_requested_Event bit in the event type is set. 

This event is issued with GC disabled. GC is re-enabled after WotifvEvent returns. . 

struct ( 

jint arena_id; 

i obi ect ID class_id; 

jint is^array; 

jint size; 

jofrigc.tJLP obj_id; 
1 obj_olloc; 



Contents: 
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arena id • aicna wheic allocated. 

- class to which this object belongs, or the array element class if 
class_i i 5 _array is JVMPI^CLASS. 

i s_ a r ray - values can be: 



JVMPJ 


N0FMAL_object normal object 


JVMPI 


CLASS 


array of objects 


JVMPI 


BOOLEAN 


array of boolcans 


JVMPI_ 


BYTE 


array of bytes 


JVMPI 


CHAP 


array of chars 


JVMPI_ 


SHORT 


array of shorts 


JVMPJ_ 


INT 


array of ints 


JVMPl^ 


LONG 


array of longs 


JVMPI_ 


FLOAT 


array of floats 


JVMPI_ 


DOUBLE 


array of doubles 



size - size in number of bytes. 
obj_id - unique object ID. 

JVMPI_2VENT_OBJi:CT_DUMP 

Sent when requested by the PveqoestEvent function. The jobjectlD of the object for which a 
dump is being requested should be passed as the second argument to RequestEvent. 

The profiler agent should request this event with GC disabled 

The event-specific data contains a snapshot of the object. 

struct { 

jint data_len; 

char *data; 
) ob j e c t_d ump ; 

Contents: 

data_len - length of the object dump buffer 
data - beginning of the object dump 

The format of the object dump buffer is described iri detail in the JVMPI Dump Formats 
section. 

JVMPI^EVXNT_OBJECT_FREE 

Sent when an object is freed. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via ma Hoc). 

This event is always sent between a pair of jvmpi event gc start and 

jvmpi event GC FINISH events. The profiler agent should acquire all the locks need for 
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processing this event in the event handler for jvmpi_event_gc_stakt. 

struct ( 

iobiectID obj_id; 

Contents: 

obj_id - object being freed. 

JVKP I_EVENT_OB JECT_MOVE 

Sent when an object is moved in the heap. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via malloc). 

This event is always sent between a pair of JVMPI event gc start and 

jvmpi EVENT GC FINISH events. The profiler agent should acquire all the locks need for 

processing this event in the event handler for jvmpi_evemt_GC_START. 

struct < 

jint arena_id; 
iobiectID obj_id; 
jint new_arena_id; 
j object ID new_obj_id; 
) obj_move; 

Contents: 

arena_id - current arena. 
obj_id • current object ID. 

new_arena_id - new arena. 
neu_obj_id - new object ID. 

JVMPI EVTNT_RAW_: MONXTORj CONTENDED_ENTER 

Sent when a thread is attempting to enter a raw monitor already acquired by another thread. 

struct ( 

char *name; 

JVMPI RawMonitor id; 
) rawjmonitor; 

Contents: 

name - name of the raw monitor 
id - ID of the raw monitor 

JVMPl^rVXirr_W^W_MONI TOR_CONTEKDED_ENTER£D 

Sent when a thread enters a raw monitor after waiting for it to be released by another thread. 



struct ( 

char *nam«r; 

JVMP1 RawMonltor id; 
) raw^monitoi ; 

Contents: 

name - name of the raw monitor 
id -ID of the raw monitor 

J>^lP2_KVENT_I^W_MONITOR_COHTENDED_tXIT 

Sent when a thread exits a raw monitor, and another thread is waiting to acquire the same 
monitor. . 

struct ( 

char *name; 

JVMPI_RawMonator id; 
) raw_monitor; 

Contents: 

name - name of the raw monitor 
id - ID of the raw monitor 

JVMPI_EVEKT_THREAD__END 

Sent when a thread ends in the VM. 

The env_id field of the jvwPi_Event received in this event notification is the JNlEnv interface 
pointer of the thread that ended. 

JVKPI_EVXNT_TKREAD_SXAKT 

Sent when a thread is started in the VM, or when the profiler agent requests a 

JVMP I_E VENT_T H READ_S tart event by issuing a ReouestEvent call. In the latter case, the 

jvmpi"reqUESTED_Event bit in the event type is set. 

This event is issued with GC disabled. GC is re-enabled after NotifvEvent returns. 

struct ( 

char *thread_naine; 

char *group_naxne; 

char *parent_name; 

loMectlp threaded; 

JNXEnv *thread_env_id; 
) thread_start; 

Contents: 
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thread _namc - name of thread being started, 
qroup^niimc - group to which the thread belongs, 
parent name - name of parent, 
thread id - thread object ID. 
thread_env_id - JNIEnv - of the thread. 

Threads arc associated with a JNiEnv pointer and a thread object ID. The JVMPI uses the 
JNlEnv pointer as the thread ID. 

4. Dump Formats 

4.1 Sizes and Types Used in Dump Format Descriptions 

ui : 1 byte 
u2 : 2 bytes 
u4 : 4 bytes 
us : 8 bytes 
ty: ul where: 



JVMPI 


NORMAL_OB JECT 


normal object 


JVMPI _ 


CLASS 


array of objects 


JVMPI_ 


BOOLEAN 


array of booleans 


JVMPI^ 


.BYTE 


array of bytes 


JVMPI 


CHAR 


array of chars 


JVMPI., 


_SHORT 


array of shorts 


JVMPI, 


INT 


array of ints 


JVMPI_ 


LONG 


array of longs 


JVMPI, 


FLOAT 


array of floats 


JVMPI_ 


DOUBLE 


array of doubles 



vi : values, exact size depends on the type of value: 
boolean, byte 

short, char u2 

int, float u4 

long, double u8 

JNIEnv *, jobjectID, and JVMPI_RawMonitor sizeof(void *) 



4.2 Heap Dump Format 

The heap dump format depends on the level of information requested. 

JVWPI_DUMP_LEVEL 0: 

The dump consists 6Fa sequence of records of the following format: 



♦ 



Ul 



ty type of object 

j object 3D object 

JVKPI DUMP LEVEL 1: 

The dump format islhc same as that of jvmpi dump_LEvel_2, except that the following values arc 
excluded from the dump: primitive fields in ofyect instance dumps, primitive static fields in class 
dumps, and primitive array elements. 

JVMPI DUMPJLEVEL 2; 

The dump consists 67 a sequence of records, where each record includes an 8-bit record type fplJowed 
by data whose format is specific to each record type. 



Record type 




Record data 


JVM P I _GC_ROOT_UNKNOWN 

(unknown root) 


| jobjectID 


object 


JVMPI CC ROOT JNI_GLOBAL 
(JNl global ref root) 


| jobjectID 
B j object 


object 

JNI global reference 


JVMPI GC ROOT JNI LOCAL 

(JNI local ref) 


| jobjectID 
| JNIEnv * 

|u4 


object 
thread 

frame ft in stack trace (-1 for 
empty) ! 


JVM PI _GC_ROOT_ JAVA FRAME 
(Java staclTframe) 


| jobjectID 
JNI En v * 

U4 


object 
thread 

frame # in stack trace (-1 for 
empty) 


JVMPI_GC ROOT_NATIVE_STACK 

{native stack) 


jobjectID 
|jNIEnv ♦ 


object 
thread 


JVM P I_GC_ROOT_S T I CKYJCIAS S 
(systenTclass) 


jobjectID 


class object 


JVMP I_GC_ROOT_THREAD_BLOCK 
(reference from thread block) 


jobjectID 
JNIEnv ♦ 


thread object 
thread 


JVM P I _GC_ROOT_MON I TORSOS ED 

"(entered monitor) ~ 


jobjectID 


object 


JVMPI_GC_CLASS_DUMP 

(dump of a class object) 


jobjectID 
jobjectID 
jobjectID 
jobjectID 
jobjectID 
void * 
void * 
u4 

t jobjectID) 
u2 
[u2, 
ty, 


class 
super 

class loader 
signers 

protection domain 

reserved 

reserved 

instance size (in bytes) 
interfaces 

size of constant pool 
constant pool index, 

type, 
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• 




I Vl) * 


value 

static field values 


JVMPI_GC INSTANCE DUMP 

(dump of'a normal ooject) 


J jobjectID 
jobjectID 

|vl]- 


object 
class 

number of bytes that follow 
instance field values (class, . 
followed by super, super's 
super ...) 


JVM P I _GC OBJ ARRAY_DUMP 
(dump oT an object array) 


jobjcctID 
u4 

jobjectID 
(jobjectID)* 


array object 
number of elements 
element class ID (may be 
null in JDK 1.2) 
elements 


JVMPI GC PRIM ARRAY DUMP 

(dump of a primitive array) 


jobjectID 
u4 

ty 

(vl)* 


array object 1 
number of elements 
element type 
elements 



4.3 Object Dump Format 

The dump buffer consists of a single record which includes an 8-bit record type, followed by data 
specific to the record type. The record type can be one of the following: 

• JVMPI_GC_CLASS_DUMP 

• J\nflPI~GC~INSTANC£_DUMP 

• JVMP I_GC_OB J_ARRA Y_DUM P 

The format of the data for each record type is the same as described above in the heap dump format 
section. The level of information is the same as *Jvmpi_dump LEvel_2. with all of the following 
values included: primitive fields in object instance dumps,,pnmitive static fields in class dumps, and 
primitive arrays elements. 

4.4 Monitor Dump Format 

The dump buffer consists of a sequence of records, where each record includes an 8-bit record type 
followed by data whose format is specific to each record type. 



| Record type 


Record data 


1 

JVMPI MONITOR JAVA 

~ 1 


jobjectID object ID 

JNlEnv * owner thread 

u4 entry count 

u4 number of threads waiting to enter 

C JNiEnv *)♦ threads waiting to enter 

u4 number of threads waiting to be 
notified 

( JNlEnv • • J • threads waiting to be notified 
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JVMPI_MONITOB_RAW 

(Raw monitor) 



char * 

JVMP3 wMoni t ox 

JNIEnv * 

u4 

u4 

u4 

[JNIEnv * J * 



raw monitor name 
raw monitor ID 
owner thread 
entry count 

number of threads waiting to enter 
threads waiting to enter, 
number of threads waiting to be 
notified 

threads waiting to be. notified 



5. Data Types 

Characters are encoded using the UTF-8 encoding as documented in the Java virtual machine 
specification. 

jebjectID 

An opaque pointer representing an object ID. 
struct _jobjectID; 

typedef struct _jobjectID ♦ jebjectID; 
JVMPI_CallFra»e 

A method being executed 

typedef struct ( 

jint lineno; 

j method ID method_id; 
) JVMPI_CallFrame; 

Fields: 

line number * line number in the source file. 
method_id - method being executed. 

JVMPI_CallTraee 

A call trace of method execution. 



typedef struct { 

JNIEnv *env_id; 

jint num_frait>ee; 

JVMPI Call Frame 'frames; 
) JVMP3 CallTrace; 



Fields: 
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cnv i d - ED of thread which executed this trace. 
num_ frames - number of frames in the trace. 

-the JVMPI Col) Frame s that make up this tiacc. Callcc followed by 
'" mc * caJleH - 

JVKPI^Field 

A field defined in a class. 

typedef struct { 

char *f ield_naroe; 

char *rieid_5ignature; 
) JVMPl_Field; 

Fields: 

field_name - name of field 
field^signatur* - signature of field 

JVMP I_He apDunpAxg 

Additional info for requesting heap dumps. 

typedef struct { 

jint heap_dump_level; 
) JVMPI_HeapDuxnpArg; 

Fields: 

heap^dump^ievei - level of heap dump information, values can be: 

JVMPI_DUMP_LEVEL_0 
JVMPI_DUMPJLEVEL_1 
JVMPI DUMP LEVEL 2 

JVMPI_LineJi© 

A mapping between source line number and offset from the beginning of a compiled method. 

typedef struct { 

jint offset; 

jint lineno ; 
1 JVMPI_Lineno; 

Fields: 

offset - offset from beginning of method 
lineno - lineno from beginning of source file 

JVMPi_Method 



A method defined in a class. 

typedel struct ( 

char *met hod^name; 

char * met hod_signa cure; 

jint stert_lineno; 

jint end_lineno; 

jmethodlD method _id; 
> JVMPIJtethod; 

Fields: 

■ method name - name of method 
method_signature - signature of method 
start_lineno - start line number in the source file 
end_l i neno - end line number in the source file 

method_id - ID given to this method 

.7VMP I_RawMoni tor 

An opaque pointer representing a raw monitor, 
struct _JVMPl_RawMonitor; 

typedef struct _JVMPI_RawMonitor * JVMPl_RawMonitor ; 

6. Notes on JDK1.2 Implementation Limitations 

• jvmpi_event_object_ALLoc events for object arrays are issued with unknown element class 
IDs (i.e., the class_id field is always null). 

• On Win32 the following events are not yet supported in the presence of the JIT compiler 

JVMPI_EVENT_METHQD_ENTRy, 
JVMPI_EVENT_METHOD ENTRY 2, 
JVMP I~E VENT^METHOD^EX I T, 
JVMPI^EVENT^COHPILED^METHOD^LOAD. and 

jvmpi"event2compiled2method_unload, 

• SuspendThread must be called with the GC is disabled. GC must remain disabled until all 
threads have been resumed. 

• The thread start event for the main thread (first thread the VM creates) may arrive after some 
other events that refer to its JNIEnv interface pointer. 

• jvmpi_event_arena_new and JVWPI_event_arena_delete events are never issued. Arena 
IDs in other events are always set to H 
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